<p>
	Datepicker will help you with date selection. It can be used either inline with <code>NgbDatepicker</code> component
	or as a popup on any input element with <code>NgbInputDatepicker</code> directive. It also comes with the list of
	services to do date formatting, i18n and <a routerLink="../calendars">alternative calendars support</a>.
</p>
<p>
	We try to keep API of our components simple, but introduce extension points, so you could enrich and reuse them. Here
	is a short example of the vacation range picker that displays holidays with tooltips and disables weekends.
</p>

<ngbd-datepicker-demo-overview class="d-block my-4"></ngbd-datepicker-demo-overview>

<!-- BASIC USAGE -->
<ngbd-page-header fragment="basic-usage" [title]="overview['basic-usage']">
	<p>Datepicker can be used either inline or inside of the popup.</p>

	<ngbd-code [snippet]="snippets.basic"></ngbd-code>

	<p>
		In the example above the template variable <code>#d</code> will point to the instance of the
		<code>NgbDatepicker</code> component in the first case. In the second it will point to the instance of the
		<code>NgbInputDatepicker</code>
		directive that handles the popup with inline datepicker component.
	</p>

	<p>
		See the <a routerLink="../api" fragment="NgbDatepicker">NgbDatepicker API</a> and the
		<a routerLink="../api" fragment="NgbInputDatepicker">NgbInputDatepicker API</a>
		for details on available inputs, outputs and methods. You can customize the number of displayed months, the way
		navigation between months and years looks like, week numbers, etc.
	</p>

	<p>
		Since v5.2.0 datepicker also has the
		<a routerLink="../api" fragment="NgbDatepickerState">State interface</a>
		accessible via <code>datepicker.state</code> getter. It represents the readonly part of the publicly accessible
		state. ex. what is currently focused, what is the first and last visible dates, etc.
	</p>

	<p>
		If you have a very specific use case for the datepicker popup, you could always create you own one and use the
		inline datepicker inside.
	</p>

	<h4>Handling the popup</h4>

	<p>
		It's up to you do decide when the datepicker popup should be opened and closed. The API contains
		<code>.open()</code>, <code>.close()</code> and <code>.toggle()</code>
		methods.
	</p>

	<p>
		By default the popup element is attached after the input in the DOM. You have also the option of attaching it to the
		document body by setting the
		<code>[container]</code> input to <code>'body'</code>
	</p>

	<ngbd-code [snippet]="snippets.popup"></ngbd-code>

	<p>
		The popup will be closed with <code>Escape</code> key and when a date is selected via keyboard or mouse. It can stay
		open after date selection if you set <code>[autoClose]</code> input to <code>false</code>
	</p>

	<p>
		When using a button (or any other element) to open the popup, the styling and content of the button is left up to
		you. In the example above, the button is simply given the text "Toggle", but you could also use an icon, or even
		group the
		<code>input</code> and <code>button</code> with an
		<a href="https://getbootstrap.com/docs/{{ bootstrapVersion }}/components/input-group/#button-addons">input group</a
		>.
	</p>
</ngbd-page-header>

<!-- GETTING / SETTING A DATE -->
<ngbd-page-header fragment="getting-date" [title]="overview['getting-date']">
	<p>
		You have several ways of knowing when user selects a date. The date is selected either by clicking on it, pressing
		<code>Space</code> or <code>Enter</code>, typing text in the input or programmatically.
	</p>

	<p>
		Datepicker is integrated with Angular forms and works with both reactive and template-driven forms. So you could use
		<code>[(ngModel)]</code>, <code>[formControl]</code>, <code>formControlName</code>, etc. Using
		<code>ngModel</code> will allow you both to get and set selected value.
	</p>

	<p>
		The model, however, is NOT a native javascript date, see the following
		<a routerLink="./" fragment="date-model">Date Model</a> section for more info.
	</p>

	<ngbd-code [snippet]="snippets.form"></ngbd-code>

	<p>
		Alternatively you could use the <code>(dateSelect)</code> output. The difference from <code>ngModel</code> is that
		outputs will continue emitting the same value, if user clicks on the same date. <code>NgModel</code> will do it only
		once.
	</p>

	<ngbd-code [snippet]="snippets.selection"></ngbd-code>
</ngbd-page-header>

<!-- DATE MODEL-->
<ngbd-page-header fragment="date-model" [title]="overview['date-model']">
	<p>
		Datepicker uses <a routerLink="../api" fragment="NgbDateStruct"><code>NgbDateStruct</code></a> interface as a model
		and not the native <code>Date</code> object. It's a simple data structure with 3 fields, but note that months start
		with 1 (as in ISO 8601).
	</p>

	<ngbd-code [snippet]="snippets.dateStruct"></ngbd-code>

	<p>
		All datepicker APIs will consume <code>NgbDateStruct</code>, but will produce it's implementation class
		<a routerLink="../api" fragment="NgbDate"><code>NgbDate</code></a> when returning dates to you. It offers additional
		methods for easy date comparison, and using it together with
		<a routerLink="../api" fragment="NgbCalendar"><code>NgbCalendar</code></a> will cover most of the date-related
		calculations.
	</p>

	<ngbd-code [snippet]="snippets.date"></ngbd-code>

	<h4>Adapters</h4>

	<p>
		You can also tell datepicker to use the native JavaScript date adapter (bundled with ng-bootstrap). For now the
		adapter works only for the form integration, so for instance <code>(ngModelChange)</code> will return a native date
		object. All other APIs continue to use <code>NgbDateStruct</code>.
	</p>

	<ngbd-code [snippet]="snippets.nativeAdapter"></ngbd-code>

	<p>
		You can also create your own adapters if necessary by extending and implementing the
		<code>NgbDateAdapter</code> methods, as in
		<a routerLink="../examples" fragment="adapter">custom date adapter example</a>.
	</p>

	<ngbd-code [snippet]="snippets.adapter"></ngbd-code>

	<h4>Input date parsing and formatting</h4>

	<p>
		In the case of the <code>NgbInputDatepicker</code> you should be able to parse and format the text entered in the
		input. This is not as easy task as it seems, because you have to account for various formats and locales. For now
		internally there is a service that does default formatting using ISO 8601 format.
	</p>

	<ngbd-code [snippet]="snippets.formatter"></ngbd-code>

	<p>If the entered input value is invalid, the form model will contain the entered text.</p>

	<p>
		You can also create your own parser or formatter if necessary by extending and implementing the
		<code>NgbDateParserFormatter</code> methods, as in
		<a routerLink="../examples" fragment="adapter">custom date parser formatter example</a>.
	</p>
</ngbd-page-header>

<!-- MOVING AROUND-->
<ngbd-page-header fragment="navigation" [title]="overview['navigation']">
	<p>
		Date selection and navigation are two different things. You might have a date selected in January, but August
		currently displayed.
	</p>

	<p>
		Datepicker fully supports keyboard navigation and screen readers. You can navigate between controls using
		<code>Tab</code> (focus will be trapped in the popup), move date focus with arrow keys, home, page up/down and use
		<code>Shift</code> modifier for faster navigation.
	</p>

	<p>
		With the API you can tell datepicker to initially open a specific month via the <code>[startDate]</code> input or go
		to any month via the <code>.navigateTo()</code> method
	</p>

	<ngbd-code [snippet]="snippets.navigation"></ngbd-code>
</ngbd-page-header>

<!-- DISABLING/LIMITING DATES-->
<ngbd-page-header fragment="limiting-dates" [title]="overview['limiting-dates']">
	<p>
		You can limit the dates available for navigation and selection using
		<code>[minDate]</code> and <code>[maxDate]</code> inputs. If you don't specify any of them, you'll have infinite
		navigation and the year select box will display [-10, +10] years from currently visible month.
	</p>

	<p>
		If you want to disable some dates for selection (ex. weekends), you have to provide the
		<code>[markDisabled]</code> function that will mark certain dates not selectable. It will be called for each newly
		visible day when you navigate between months.
	</p>

	<ngbd-code style="position: relative; top: 0.25rem" [snippet]="snippets.disablingTS"></ngbd-code>
	<ngbd-code style="position: relative; bottom: 0.25rem" [snippet]="snippets.disablingHTML"></ngbd-code>
</ngbd-page-header>

<!-- DAY CUSTOMIZATION-->
<ngbd-page-header fragment="day-template" [title]="overview['day-template']">
	<p>
		You can completely replace how each date is rendered by providing a custom template and rendering anything you want
		inside. You'll get a date context available inside the template with info on whether current date is disabled,
		selected, focused, etc.
	</p>

	<p>
		For more info on what is provided in the template context, see the
		<a routerLink="../api" fragment="DayTemplateContext">DayTemplateContext API</a>
	</p>

	<ngbd-code [snippet]="snippets.dayTemplate"></ngbd-code>

	<ngb-alert class="mt-3" [dismissible]="false">
		Note that before v3.3.0 there is no <code>$implicit</code> template property and you have to specify
		<code>let-date="date"</code> in the template. See
		<a href="https://angular.dev/api/common/NgTemplateOutlet#example">$implicit example</a> in Angular documentation.
	</ngb-alert>
</ngbd-page-header>

<!-- TODAY'S DATE -->
<ngbd-page-header fragment="today" [title]="overview['today']">
	<p>
		It is often useful to highlight a today's date in the calendar view or add a certain logic to it. Today's date is
		the date returned by the <a routerLink="../api" fragment="NgbCalendar">NgbCalendar</a>'s
		<code>getToday()</code>
		method.
	</p>

	<p>
		We add a custom CSS class <code>.ngb-dp-today</code> on a cell that corresponds to the today's date. We do not add
		any rules to it at the moment, but you can add your own if necessary. You would see something like this in the
		resulting markup
	</p>

	<ngbd-code [snippet]="snippets.todayHTML"></ngbd-code>

	<p>
		You can also access this information from the
		<a routerLink="../api" fragment="DayTemplateContext">DayTemplateContext API</a> if you're using a custom day
		template. It contains a <code>today: boolean</code> flag since v4.1.0
	</p>

	<ngbd-code [snippet]="snippets.todayTemplate"></ngbd-code>
</ngbd-page-header>

<!-- MONTH LAYOUT CUSTOMIZATION-->
<ngbd-page-header fragment="content-template" [title]="overview['content-template']">
	<p>
		You can replace the content of the datepicker. Combined with the NgbDatepickerMonthView you can customize the layout
		of months as in the
		<a routerLink="../examples" fragment="custommonth">custom month layout example</a>.
	</p>

	<ngbd-code [snippet]="snippets.contentTemplate"></ngbd-code>
</ngbd-page-header>

<!-- FOOTER TEMPLATE -->
<ngbd-page-header fragment="footer-template" [title]="overview['footer-template']">
	<p>You can insert anything you want in a datepicker footer by providing a template.</p>

	<ngbd-code [snippet]="snippets.footerTemplate"></ngbd-code>
</ngbd-page-header>

<!-- RANGE SELECTION -->
<ngbd-page-header fragment="range" [title]="overview['range']">
	<p>
		The datepicker model is a single date, however you still can implement range selection functionality. With
		<code>(select)</code> and <code>(dateSelect)</code> outputs you'll know which dates are being selected and with the
		<code>[dayTemplate]</code> input you can customize the way any particular date looks. If you want to use the
		<code>NgbDatepickerInput</code>, you can also tell the popup to stay open by tuning the
		<code>[autoClose]</code> input. Check the
		<a routerLink="../examples" fragment="range">range selection example</a>
		and the initial demo on this page for more details.
	</p>

	<p>
		If you can't use the <code>NgbDatepickerInput</code> directive, you should create your own popup and use
		<code>NgbDatepicker</code> inside of it. In this case we'll handle everything related to date selection and
		navigation for you and you can create a completely customized popup with any data model you want.
	</p>
</ngbd-page-header>

<!-- I18N -->
<ngbd-page-header fragment="i18n" [title]="overview['i18n']">
	<p>
		Since the 2.0.0 release datepicker will use the
		<a href="https://angular.dev/guide/i18n/locale-id#set-the-source-locale-id">application locale</a>
		if it is present to get translations of weekdays and month names. The internal service that does translation is
		called
		<code>NgbDatepickerI18n</code> and you could provide your own implementation if necessary.
	</p>

	<ngbd-code [snippet]="snippets.i18n"></ngbd-code>

	<p>
		The next/previous button labels can be translated using the standard Angular i18n mechanism. For example, previous
		month label is extracted under the <code>ngb.datepicker.previous-month</code>
		name.
	</p>
</ngbd-page-header>

<!-- Keyboard -->
<ngbd-page-header fragment="keyboard-shortcuts" [title]="overview['keyboard-shortcuts']">
	<p>
		You can customize keyboard navigation as in the
		<a routerLink="../examples" fragment="keyboard">custom keyboard navigation example</a>. The default keys are as
		follows:
	</p>

	<table class="table mt-4">
		<tbody>
			<tr>
				<td><code>Space / Enter</code></td>
				<td>Selects currently focused date if it is not disabled</td>
			</tr>
			<tr>
				<td><code>Escape</code></td>
				<td>Closes the datepicker popup (unless <code>[autoClose]</code> is false)</td>
			</tr>
			<tr>
				<td><code>Arrow(Up|Down|Left|Right)</code></td>
				<td>Moves day focus inside the months view</td>
			</tr>
			<tr>
				<td><code>Shift + Arrow(Up|Down|Left|Right)</code></td>
				<td>Selects currently focused date (if it is not disabled)</td>
			</tr>
			<tr>
				<td><code>Home</code></td>
				<td>Moves focus to the the first day of currently opened first month</td>
			</tr>
			<tr>
				<td><code>End</code></td>
				<td>Moves focus to the the last day of currently opened last month</td>
			</tr>
			<tr>
				<td><code>Shift + Home</code></td>
				<td>Moves focus to the <code>minDate</code> (if set)</td>
			</tr>
			<tr>
				<td><code>Shift + End</code></td>
				<td>Moves focus to the <code>maxDate</code> (if set)</td>
			</tr>
			<tr>
				<td><code>PageDown</code></td>
				<td>Moves focus to the previous month</td>
			</tr>
			<tr>
				<td><code>PageUp</code></td>
				<td>Moves focus to the next month</td>
			</tr>
			<tr>
				<td><code>Shift + PageDown</code></td>
				<td>Moves focus to the previous year</td>
			</tr>
			<tr>
				<td><code>Shift + PageUp</code></td>
				<td>Moves focus to the next year</td>
			</tr>
		</tbody>
	</table>
</ngbd-page-header>
